---
title: 概述
description: 模型上下文协议（MCP）Java SDK 简介
---

[模型上下文协议](https://modelcontextprotocol.org/docs/concepts/architecture) 的 Java SDK 支持 AI 模型与工具之间的标准化集成。

<Note>
### 0.8.x 版本的重大变更 ⚠️
**注意：** 0.8.x 版本引入了多项重大变更，包括基于会话的新架构。
如果您从 0.7.0 版本升级，请参阅 [迁移指南](https://github.com/modelcontextprotocol/java-sdk/blob/main/migration-0.8.0.md) 以获取详细说明。
</Note>

## 功能

- 支持 MCP 客户端和 MCP 服务器实现，包括：
  - 协议 [版本兼容性协商](/specification/2024-11-05/basic/lifecycle/#initialization)
  - [工具](/specification/2024-11-05/server/tools/) 发现、执行、列表变更通知
  - 使用 URI 模板进行 [资源](/specification/2024-11-05/server/resources/) 管理
  - [根路径](/specification/2024-11-05/client/roots/) 列表管理和通知
  - [提示](/specification/2024-11-05/server/prompts/) 处理和管理
  - 支持 AI 模型交互的 [采样](/specification/2024-11-05/client/sampling/)
- 多种传输实现：
  - 默认传输（包含在核心 `mcp` 模块中，无需外部 Web 框架）：
    - 基于标准输入输出的传输，用于进程间通信
    - 基于 Java HttpClient 的 SSE 客户端传输，支持 HTTP SSE 客户端流式传输
    - 基于 Servlet 的 SSE 服务器传输，支持 HTTP SSE 服务器流式传输
  - 可选的基于 Spring 的传输（在使用 Spring 框架时提供便利）：
    - 基于 WebFlux 的 SSE 客户端和服务器传输，支持反应式 HTTP 流式传输
    - 基于 WebMVC 的 SSE 传输，支持基于 Servlet 的 HTTP 流式传输
- 支持同步和异步编程范式

<Tip>
核心 `io.modelcontextprotocol.sdk:mcp` 模块提供了默认的标准输入输出和 SSE 客户端及服务器传输实现，无需外部 Web 框架。

在使用 [Spring 框架](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html) 时，可选择添加 Spring 特定的传输依赖以提供便利。
</Tip>

## 架构

SDK 采用分层架构，职责划分清晰：

![MCP 堆栈架构](/images/java/mcp-stack.svg)

- **客户端/服务器层（McpClient/McpServer）**：两者均使用 McpSession 进行同步/异步操作，McpClient 处理客户端协议操作，McpServer 管理服务器端协议操作。
- **会话层（McpSession）**：使用 DefaultMcpSession 实现管理通信模式和状态。
- **传输层（McpTransport）**：通过以下方式处理 JSON-RPC 消息序列化/反序列化：
  - 核心模块中的 StdioTransport（标准输入/输出）
  - 专用传输模块中的 HTTP SSE 传输（Java HttpClient、Spring WebFlux、Spring WebMVC）

MCP 客户端是模型上下文协议（MCP）架构中的关键组件，负责与 MCP 服务器建立和管理连接。
它实现了协议的客户端部分。

![Java MCP 客户端架构](/images/java/java-mcp-client-architecture.jpg)

MCP 服务器是模型上下文协议（MCP）架构中的基础组件，为客户端提供工具、资源和功能。
它实现了协议的服务器端部分。

![Java MCP 服务器架构](/images/java/java-mcp-server-architecture.jpg)

关键交互：

- **客户端/服务器初始化**：传输设置、协议兼容性检查、能力协商和实现细节交换。
- **消息流**：JSON-RPC 消息处理，包括验证、类型安全的响应处理和错误处理。
- **资源管理**：资源发现、基于 URI 模板的访问、订阅系统和内容检索。

## 依赖项

将以下 Maven 依赖项添加到您的项目中：

<Tabs>
  <Tab title="Maven">
核心 MCP 功能：

```xml
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp</artifactId>
</dependency>
```

核心 `mcp` 模块已包含默认的标准输入输出和 SSE 传输实现，无需外部 Web 框架。

如果您使用 Spring 框架并希望使用 Spring 特定的传输实现，可添加以下任一可选依赖项：

```xml
<!-- 可选：基于 Spring WebFlux 的 SSE 客户端和服务器传输 -->
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-spring-webflux</artifactId>
</dependency>

<!-- 可选：基于 Spring WebMVC 的 SSE 服务器传输 -->
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-spring-webmvc</artifactId>
</dependency>
```
  </Tab>
  <Tab title="Gradle">
核心 MCP 功能：

```groovy
dependencies {
    implementation platform("io.modelcontextprotocol.sdk:mcp")
    //...
}
```

核心 `mcp` 模块已包含默认的标准输入输出和 SSE 传输实现，无需外部 Web 框架。

如果您使用 Spring 框架并希望使用 Spring 特定的传输实现，可添加以下任一可选依赖项：

```groovy
// 可选：基于 Spring WebFlux 的 SSE 客户端和服务器传输
dependencies {
    implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webflux")
}

// 可选：基于 Spring WebMVC 的 SSE 服务器传输
dependencies {
    implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webmvc")
}
```
  </Tab>
</Tabs>

### 物料清单（BOM）

物料清单（BOM）声明了给定版本推荐使用的所有依赖项版本。
在您的应用程序构建脚本中使用 BOM 可以避免您自行指定和维护依赖项版本。
相反，您使用的 BOM 版本决定了依赖项的版本。
这还能确保您默认使用支持且经过测试的依赖项版本，除非您选择覆盖它们。

将 BOM 添加到您的项目中：

<Tabs>
  <Tab title="Maven">
```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.modelcontextprotocol.sdk</groupId>
            <artifactId>mcp-bom</artifactId>
            <version>0.9.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```
  </Tab>

  <Tab title="Gradle">
```groovy
dependencies {
    implementation platform("io.modelcontextprotocol.sdk:mcp-bom:0.9.0")
    //...
}
```

Gradle 用户还可以利用 Gradle（5.0+）对声明 Maven BOM 的依赖约束的原生支持。
通过在 Gradle 构建脚本的依赖项部分添加 'platform' 依赖处理方法实现，如上所示。
随后可以添加一个或多个您希望使用的 spring-ai 模块的无版本声明的 Starter 依赖，例如 spring-ai-openai。
  </Tab>
</Tabs>

将版本号替换为您希望使用的 BOM 版本。

### 可用依赖项

以下依赖项可用并由 BOM 管理：

- 核心依赖项 
  - `io.modelcontextprotocol.sdk:mcp` - 核心 MCP 库，提供模型上下文协议实现的基本功能和 API，包括默认的标准输入输出和 SSE 客户端及服务器传输实现。无需外部 Web 框架。
- 可选传输依赖项（在使用 Spring 框架时提供便利）
  - `io.modelcontextprotocol.sdk:mcp-spring-webflux` - 基于 WebFlux 的服务器发送事件（SSE）传输实现，适用于反应式应用。
  - `io.modelcontextprotocol.sdk:mcp-spring-webmvc` - 基于 WebMVC 的服务器发送事件（SSE）传输实现，适用于基于 Servlet 的应用。
- 测试依赖项
  - `io.modelcontextprotocol.sdk:mcp-test` - 为基于 MCP 的应用提供测试工具和支持。
